Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/program/argv_akp.txt

Text File | 1994-08-27 | 20KB | 466 lines

------------------------------

Date: 9 May 91 21:18:36 GMT
From: imagen!atari![e-mail] (Allan Pratt)
Subject: ARGV spec repost as promised
To: [e-mail]

In a discussion about Pexec and command lines, the question of the
ARGV standard came up.  Here is our documentation on this convention.
It dates from August 22, 1990.

GEMDOS EXTENDED ARGUMENT (ARGV) SPECIFICATION

Introduction

The Pexec() function of GEMDOS allows a program to pass to a child
process a command line up to 125 characters long, with arguments
separated by spaces.  No provision is made in GEMDOS for the child to
know its own name.  This makes it difficult for C programs to correctly
fill in argv[0], the standard place where a C program finds the command
which invoked it.  Because the command line arguments are separated by
spaces, it is difficult to pass an argument with an embedded space.
This document will specify a method of passing arguments which allows
arbitrary argument length, embedded spaces, and support for argv[0].

Standard Argument Passing

The Pexec Cookbook specifies how to use Pexec() to launch a child
process, passing a command tail (argument string) and an environment.
Before getting into the extended argument scheme, let's review how
arguments are normally passed to a child.

A parent process builds a command line into an argument string - a null
terminated string whose first byte contains the length of the rest of
the string - and its address is passed as one of the arguments to
Pexec().  GEMDOS copies this argument string to the basepage which it
creates for the child.  Thus the parent is responsible for gathering
all the child's arguments into one string.  This is normally handled by
a library exec() function.  The child is responsible for parsing the
string of space-separated arguments back into an array of strings.
This parsing is normally handled by the child's startup code.

Evolution

Several methods of bypassing the limits imposed by Pexec() have been
used by GEMDOS programs.  Some allow a user to specify a file on the
command line which contains the rest of the arguments.  Others get a
pointer to the arguments, or the arguments themselves, from the
environment string.  Most MS-DOS programs use a command file for the
extra arguments.  This can be inconvenient for a user, cluttering the
file system with command files, and making the operation of batch files
and makefiles more confusing.

Several "standards" have arisen on the ST which use the environment to
pass arguments.  While more convenient than command files, these
standards have other problems.  Some rely on sharing memory between
parent and child processes.  Some take advantage of undocumented
features of the operating system to get argv[0].  Others give the
child process no way to validate that the arguments it finds are
intended for it.

Rationale

In order to pass more than the standard 125 characters worth of
arguments to a child, or to let the child find its name, the parent
must place the extra information in a place where the child can access
it safely and legally.  The most convenient place is in the child's
environment string.  An environment string is a series of
null-terminated strings of the format "VARIABLE=value" (e.g.
PATH=c:\bin,c:\etc, or ShellP=YES).   The last null-terminated string
in the environment is followed by a zero byte, thus two consecutive
nulls indicates the end of the environment.   The environment is
allocated for the child by GEMDOS, it is owned by the child, and its
contents can be specified by the parent.

The child must have some way of knowing that the arguments which
it finds in its environment are intended for it.  The child may have
been invoked by a parent which does not conform to this specification.
Such a parent would leave _its_ arguments in the environment, and could
pass that environment on to the child.  The child would mistakenly
interpret its parent's arguments as its own.

Placing arguments in the environment passed to the child gets around
all of the command line limits of the standard Pexec() command tail.
Because there is no limit on the length of the environment, arbitrary
length arguments are supported.  Arguments placed in the environment
are null terminated, so they may contain spaces.  A parent can also
place the name of the command with which it invokes the child in the
child's environment, providing support for argv[0].  Validation of the
extended arguments can be placed in the standard Pexec() command line,
by assigning a special meaning to an invalid length byte.

The GEMDOS Extended Argument Specification

This specification uses the convention that the presence of an
environment variable named ARGV (all upper case) indicates that extended
arguments are being passed to the child in its environment.  This means
that ARGV is a "boolean" environment variable.  For the purpose of this
specification, its value is not significant, but its presence indicates
that the strings following it are the arguments for the child.
Implementations of this specification are free to give the ARGV
environment variable any value.  The ARGV environment variable must be
the last one in the environment passed to the child, so that the child
can truncate its environment at that point, and treat everything before
the ARGV as environment, and everything after it as arguments.

The first argument to the child (argv[0]) is the first string in the
environment after the ARGV variable.  This argument is the "pathname"
parameter passed by the parent to Pexec().  The remaining arguments are
those that the child would normally find in the command tail in its
basepage.  Even if all of the arguments would normally fit in a child's
command tail, the parent should set up the arguments in the environment
to take advantage of the benefits of this extended argument scheme.

As many arguments as will fit in the command tail will be passed there
as well as in the environment, to support non-conforming programs.  As
a flag that arguments are also in the environment, the length byte of
the command tail will be 127 (hex 7f).  Non-conforming programs should
not have a problem with this length byte, because it is longer than the
maximum 125 bytes allowed by Pexec().

As an aside, the Pexec Cookbook erroneously implies that a command line
can be 126 or 127 characters long.  In fact, GEMDOS only copies to the
child's basepage up to 125 bytes, or until it encounters a null, from
the argument string passed to Pexec().  It ignores the length byte,
placing a null at the same place it found one or at the 126th byte if
no null is found.  This has several implications: the length byte is
not validated by GEMDOS (necessitating validation in the child's
startup code, but also making this extended argument spec possible),
and the null terminator _can_ be located after the end of the real
command tail (the Desktop places a CR character after the command tail
and before the null).  The ARGSTART.S startup code listing below
demonstrates how to correctly validate and parse a GEMDOS command tail.

A child which finds an ARGV environment variable can use the command
tail length byte value of 127 to validate that the arguments following
the variable are valid, and not just left over from a non-conforming
parent which left its own ARGV arguments in the environment.

Because the strings in the environment following an ARGV variable are
not environment variables, a child should truncate its own environment
at the ARGV variable by changing the 'A' to a null.

Implementation: Parental Responsibilities

To pass arguments in the environment, a parent must create an
environment string for the child.  This can be achieved by first
allocating as much space as is used in the parent's own environment,
plus enough room for the ARGV variable and the arguments to the child,
and then copying the parent's environment to the newly allocated area.
Next, the ARGV variable must be appended, since it must be the last
variable in the chi